home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_curl.idb / usr / freeware / catman / p_man / cat3 / libcurl.Z / libcurl
Text File  |  2002-07-08  |  6KB  |  148 lines
  1. libcurl(3)         libcurl overview           libcurl(3)
  2.  
  3.  
  4.  
  5. NNAAMMEE
  6.        libcurl - client-side URL transfers
  7.  
  8. DDEESSCCRRIIPPTTIIOONN
  9.        This  is     an overview on    how to use libcurl in your C pro
  10.        grams. There are    specific man pages for each function men
  11.        tioned  in  here. There's also the libcurl-the-guide docu
  12.        ment for    a complete tutorial to programming with     libcurl.
  13.  
  14.        There  are  a  dozen  custom  bindings  that bring libcurl
  15.        access to your favourite    language. Look elsewhere for doc
  16.        umentation on those.
  17.  
  18.        All    applications   that   use      libcurl   should   call
  19.        _c_u_r_l___g_l_o_b_a_l___i_n_i_t_(_) exactly once before any  libcurl  func
  20.        tion  can be used. After    all usage of libcurl is    complete,
  21.        it mmuusstt call _c_u_r_l___g_l_o_b_a_l___c_l_e_a_n_u_p_(_). In between  those  two
  22.        calls, you can use libcurl as described below.
  23.  
  24.        When  using  libcurl's "easy" interface you init    your ses
  25.        sion and    get a handle, which you    use as input to    the  easy
  26.        interface  functions  you use. Use _c_u_r_l___e_a_s_y___i_n_i_t_(_) to get
  27.        the handle. There is also the so    called "multi" interface,
  28.        try the _l_i_b_c_u_r_l_-_m_u_l_t_i_(_3_)    man page for an    overview of that.
  29.  
  30.        You continue by setting all the options you  want  in  the
  31.        upcoming     transfer,  most  important among them is the URL
  32.        itself (you can't transfer anything  without  a    specified
  33.        URL  as you may have figured out    yourself). You might want
  34.        to set some callbacks as    well that will be called from the
  35.        library when data is available etc.  _c_u_r_l___e_a_s_y___s_e_t_o_p_t_(_) is
  36.        there for this.
  37.  
  38.        When all    is setup, you tell libcurl to perform the  trans
  39.        fer using _c_u_r_l___e_a_s_y___p_e_r_f_o_r_m_(_).  It will then do the entire
  40.        operation and won't return until    it is done  (successfully
  41.        or not).
  42.  
  43.        After  the transfer has been made, you can set new options
  44.        and make    another    transfer, or if    you're done, cleanup  the
  45.        session    by calling _c_u_r_l___e_a_s_y___c_l_e_a_n_u_p_(_).     If you    want per
  46.        sistant connections, you    don't  cleanup    immediately,  but
  47.        instead    run  ahead  and    perform    other transfers    using the
  48.        same handle. See    the chapter below for Persistant  Connec
  49.        tions.
  50.  
  51.        There  is also a    series of other    helpful    functions to use.
  52.        They are:
  53.  
  54.  
  55.           ccuurrll__vveerrssiioonn(())
  56.             displays the libcurl version
  57.  
  58.           ccuurrll__ggeettddaattee(())
  59.             converts a date    string to time_t
  60.  
  61.           ccuurrll__ggeetteennvv(())
  62.             portable environment variable reader
  63.  
  64.           ccuurrll__eeaassyy__ggeettiinnffoo(())
  65.             get information    about a    performed  trans
  66.             fer
  67.  
  68.           ccuurrll__ffoorrmmaadddd(())
  69.             helps building a HTTP form POST
  70.  
  71.           ccuurrll__ffoorrmmffrreeee(())
  72.             free   a   list      built     with  curl_form
  73.             parse()/curl_formadd()
  74.  
  75.           ccuurrll__sslliisstt__aappppeenndd(())
  76.             builds a linked    list
  77.  
  78.           ccuurrll__sslliisstt__ffrreeee__aallll(())
  79.             frees a    whole curl_slist
  80.  
  81.           ccuurrll__mmpprriinnttff(())
  82.             portable printf() functions
  83.  
  84.           ccuurrll__ssttrreeqquuaall(())
  85.             portable case insensitive string  compar
  86.             isons
  87.  
  88.  
  89. LLIINNKKIINNGG    WWIITTHH LLIIBBCCUURRLL
  90.        On  unix-like  machines,     there's a tool    named curl-config
  91.        that gets installed with    the rest of the    curl  stuff  when
  92.        'make install' is performed.
  93.  
  94.        curl-config is added to make it easier for applications to
  95.        link with libcurl and developers    to  learn  about  libcurl
  96.        and how to use it.
  97.  
  98.        Run  'curl-config  --libs'  to get the (additional) linker
  99.        options you need    to link    with the  particular  version  of
  100.        libcurl you've installed.
  101.  
  102.        For details, see    the curl-config.1 man page.
  103.  
  104. LLIIBBCCUURRLL    SSYYMMBBOOLL NNAAMMEESS
  105.        All public functions in the libcurl interface are prefixed
  106.        with 'curl_' (with a lowercase  c).  You     can  find  other
  107.        functions  in  the library source code, but other prefixes
  108.        indicate    the functions are private and may change  without
  109.        further notice in the next release.
  110.  
  111.        Only use    documented functions and functionality!
  112.  
  113. PPOORRTTAABBIILLIITTYY
  114.        libcurl works eexxaaccttllyy the same, on any of the platforms it
  115.        compiles    and builds on.
  116.  
  117. TTHHRREEAADDSS
  118.        Never ever call curl-functions  simultaneously  using  the
  119.        same  handle  from several threads. libcurl is thread-safe
  120.        and can be used in any number of    threads, but you must use
  121.        separate     curl  handles if you want to use libcurl in more
  122.        than one    thread simultaneously.
  123.  
  124. PPEERRSSIISSTTAANNTT CCOONNNNEECCTTIIOONNSS
  125.        Persistent connections means that libcurl can  re-use  the
  126.        same  connection     for several transfers,    if the conditions
  127.        are right.
  128.  
  129.        libcurl will *always* attempt to     use  persistent  connec
  130.        tions.  Whenever    you use    curl_easy_perform(), libcurl will
  131.        attempt to use an existing connection to    do the    transfer,
  132.        and  if    none  exists  it'll  open  a new one that will be
  133.        subject    for  re-use  on     a  possible  following     call  to
  134.        curl_easy_perform().
  135.  
  136.        To allow    libcurl    to take    full advantage of persistent con
  137.        nections, you should do as many of your file transfers  as
  138.        possible     using    the  same  curl     handle.  When    you  call
  139.        curl_easy_cleanup(), all     the  possibly    open  connections
  140.        held by libcurl will be closed and forgotten.
  141.  
  142.        Note  that the options set with curl_easy_setopt() will be
  143.        used in on every    repeat curl_easy_perform() call
  144.  
  145.  
  146.  
  147. libcurl    7.9.6          19 March 2002               libcurl(3)
  148.